Fix documentation discrepancies with actual code behavior #166
Conversation
Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>
Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>
Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>
Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR aims to fix documentation discrepancies between documented features and actual code behavior. While many corrections are accurate (such as removing the incorrect / prefix from task invocations, correcting file search paths, and documenting the undocumented [user-prompt] argument), the PR ironically introduces significant new false claims about agent-based rule filtering.
Key Issues
Critical Problem: The updated documentation now incorrectly claims that the -a agent flag automatically adds the agent as a selector for rule filtering. This is not implemented in the code:
- The
ShouldExcludePathmethod exists inagent.gobut is never called - The agent value is never added as a selector via
cc.includes.SetValue("agent", ...) - Test code explicitly states at line 533: "Agent filtering is not implemented, so all rules are included"
- The agent is only used for: 1) determining write paths with
-wflag, and 2) being stored in the result
Consistency Issue: The flag description in main.go line 38 still states "(excludes rules from other agents)" which contradicts the PR's intent to remove false claims about exclusion.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| main.go | Updates -w flag description to clarify agent source (task field or -a flag) |
| docs/reference/cli.md | Major rewrite of agent flag documentation - introduces false claims about automatic selector addition |
| docs/reference/search-paths.md | Correctly removes .opencode/command/ and .opencode/rules/ from rule paths, adds .augment/guidelines.md |
| docs/reference/file-formats.md | Corrects task/command file locations and removes incorrect / prefix from examples |
| docs/how-to/create-tasks.md | Removes incorrect / prefix from task invocation examples |
| docs/how-to/github-actions.md | Removes incorrect / prefix from example |
| docs/index.md | Removes incorrect / prefix from example |
| README.md | Extensive updates including [user-prompt] documentation - introduces false claims about agent filtering |
Comments suppressed due to low confidence (1)
README.md:556
- This example documentation is misleading. It shows a generic rule with
agent: cursorin frontmatter and suggests this will filter rules based on agent, but the code does not implement agent-based rule filtering. The agent value from -a flag or task frontmatter is not added as a selector, so rules withagent:fields in their frontmatter will not be filtered unless you explicitly use-s agent=cursoron the command line.
**Example generic rule with agent filtering:**
```markdown
---
agent: cursor
---
# This rule only applies when using Cursor
Use Cursor-specific features...
Agent field in task frontmatter:
Tasks can specify an agent field in their frontmatter, which overrides the -a command-line flag:
---
agent: cursor
---
# This task automatically sets the agent to cursor
docs/reference/cli.md
Outdated
| Specify the target agent being used. This information is used for: | ||
| 1. **Rule Filtering**: The agent name is automatically added as a selector, allowing rules to filter based on agent | ||
| 2. **Write Rules Mode**: With `-w` flag, determines where to write rules |
There was a problem hiding this comment.
This documentation claims "The agent name is automatically added as a selector, allowing rules to filter based on agent" but this is incorrect. The code in pkg/codingcontext/context.go never adds the agent as a selector. The agent is only: 1) stored from the task frontmatter or -a flag (line 146 in context.go), and 2) returned in the result (line 322 in context.go). There is no code that calls cc.includes.SetValue("agent", ...) to add it as a selector. The test file even has a comment at line 533 stating "Agent filtering is not implemented, so all rules are included". The documentation should state that the agent is stored for use by the caller (e.g., for determining write path with -w flag) but not used for rule filtering.
There was a problem hiding this comment.
Fixed in commit 315bb6b. Removed incorrect claim about agent being added as selector. Documentation now states agent is only used for -w write path determination.
docs/reference/cli.md
Outdated
| - The agent name is automatically added as a selector for rule filtering | ||
| - Rules with matching `agent` field in frontmatter are included | ||
| - Generic rules (without an agent field) are always included |
There was a problem hiding this comment.
These lines incorrectly describe how the agent flag works. Line 197 claims "The agent name is automatically added as a selector for rule filtering" but the code never does this. Lines 198-199 describe rule filtering based on agent, which doesn't happen. The actual behavior is that the agent is stored in the context (either from -a flag or task frontmatter) and returned in the result, where it's used for determining the write path when -w flag is used. The code does not add the agent as a selector, and rules are not filtered based on the agent value.
There was a problem hiding this comment.
Fixed in commit 315bb6b. Removed lines claiming agent is used for rule filtering. Documentation now accurately describes that agent value is stored in context and used only for determining write path with -w flag.
docs/reference/cli.md
Outdated
| **Example:** | ||
| ```bash | ||
| # Using Cursor - excludes .cursor/ paths, includes others | ||
| # Specify agent for rule filtering |
There was a problem hiding this comment.
This line incorrectly states "Specify agent for rule filtering" but the agent is not used for rule filtering in the codebase. The agent flag is used to: 1) set the agent value in the context (which can be overridden by task frontmatter), and 2) determine the write path when combined with the -w flag. The code never filters rules based on the agent value.
There was a problem hiding this comment.
Fixed in commit 315bb6b. Changed example comment from "Specify agent for rule filtering" to "Use with write rules mode" which accurately reflects actual behavior.
README.md
Outdated
| - The `-a` flag sets the target agent | ||
| - The target agent's own paths are excluded (e.g., `.cursor/` for cursor) | ||
| - Rules from other agents are included (e.g., `.opencode/`, `.github/copilot-instructions.md`) | ||
| - Generic rules (from `.agents/rules`) are always included | ||
| - The agent name is automatically added as a selector, so generic rules can filter themselves with `agent: cursor` in frontmatter | ||
| - The agent name is automatically added as a selector for rule filtering | ||
| - Rules can use `agent: cursor` in frontmatter to match only when that agent is specified | ||
| - Generic rules (without an agent field) are always included |
There was a problem hiding this comment.
These lines incorrectly describe agent-based rule filtering. Lines 534-536 claim the agent name is added as a selector and that rules can filter based on agent, but this is not implemented in the code. The agent value is stored but never used for filtering rules. The test file context_test.go at line 533 has a comment confirming "Agent filtering is not implemented, so all rules are included".
There was a problem hiding this comment.
Fixed in commit 315bb6b. Removed lines 534-536 that incorrectly claimed agent is added as selector. Section now clearly states agent is only used for -w write path, with note that rule filtering is not implemented.
README.md
Outdated
| **Example: Agent-specific rules:** | ||
|
|
||
| ```bash | ||
| # When using Cursor, exclude .cursor/ and .cursorrules (Cursor reads those itself) | ||
| # But include rules from other agents and generic rules | ||
| coding-context -a cursor /fix-bug | ||
| # Specify the agent | ||
| coding-context -a cursor fix-bug | ||
| ``` |
There was a problem hiding this comment.
This example documentation incorrectly describes agent-based rule filtering. The example claims to show "Agent-specific rules" where specifying an agent filters rules, but the code does not implement this filtering. The agent flag only sets the agent value for potential use by the caller (e.g., for determining write paths with -w), but does not filter rules based on agent.
There was a problem hiding this comment.
Fixed in commit 315bb6b. Removed the "Agent-specific rules" section that incorrectly described filtering. Replaced with accurate documentation about using agent with -w flag for write mode.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
| .augment/rules/ | ||
| .windsurf/rules/ | ||
| .opencode/agent/ | ||
| .opencode/command/ |
There was a problem hiding this comment.
@copilot Can you double check the open code paths?
There was a problem hiding this comment.
The OpenCode paths are correct. Verified against paths.go:
.opencode/agent/(line 22) - for non-home rule paths.opencode/rules/(line 14) - for home directory rule paths
Both are documented correctly in search-paths.md.
docs/reference/cli.md
Outdated
| Specify the target agent being used. This information is used for: | ||
| 1. **Rule Filtering**: The agent name is automatically added as a selector, allowing rules to filter based on agent | ||
| 2. **Write Rules Mode**: With `-w` flag, determines where to write rules |
docs/reference/cli.md
Outdated
| - The agent name is automatically added as a selector for rule filtering | ||
| - Rules with matching `agent` field in frontmatter are included | ||
| - Generic rules (without an agent field) are always included |
docs/reference/cli.md
Outdated
| **Example:** | ||
| ```bash | ||
| # Using Cursor - excludes .cursor/ paths, includes others | ||
| # Specify agent for rule filtering |
README.md
Outdated
| - The `-a` flag sets the target agent | ||
| - The target agent's own paths are excluded (e.g., `.cursor/` for cursor) | ||
| - Rules from other agents are included (e.g., `.opencode/`, `.github/copilot-instructions.md`) | ||
| - Generic rules (from `.agents/rules`) are always included | ||
| - The agent name is automatically added as a selector, so generic rules can filter themselves with `agent: cursor` in frontmatter | ||
| - The agent name is automatically added as a selector for rule filtering | ||
| - Rules can use `agent: cursor` in frontmatter to match only when that agent is specified | ||
| - Generic rules (without an agent field) are always included |
README.md
Outdated
| **Example: Agent-specific rules:** | ||
|
|
||
| ```bash | ||
| # When using Cursor, exclude .cursor/ and .cursorrules (Cursor reads those itself) | ||
| # But include rules from other agents and generic rules | ||
| coding-context -a cursor /fix-bug | ||
| # Specify the agent | ||
| coding-context -a cursor fix-bug | ||
| ``` |
Agent filtering is not implemented - agent is only used for -w write path Co-authored-by: alexec <1142830+alexec@users.noreply.github.com>
Documentation Updates for Coding Context CLI - COMPLETE ✅
All Completed Tasks
Critical Issues Fixed
[user-prompt]argument-wwrite path determinationSystematic Corrections
Testing & Verification
Files Updated (3 in this commit)
docs/reference/cli.md- Removed agent filtering claimsREADME.md- Removed agent filtering claimsAll documentation now accurately reflects the actual implementation.
Original prompt
💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.